feat(transport): add non-blocking stdio_pipes transport by itsmunzir · Pull Request #1304 · modelcontextprotocol/rust-sdk

itsmunzir · 2026-09-27T12:17:44Z

Summary

transport::stdio() returns tokio::io::Stdin/Stdout, and every read and write on those handles is dispatched to Tokio's blocking thread pool. For a piped stdio server, that is a cross-thread hand-off per message: #1301 measured ~41k req/s vs ~86k over tokio::net::unix::pipe for the same server.

This adds transport::stdio_pipes() (behind the existing transport-io feature):

On Unix, when both standard streams are FIFOs — how MCP clients launch stdio servers — it duplicates the descriptors and wraps them as tokio::net::unix::pipe::{Receiver, Sender}, driven by the IO reactor.
Otherwise (TTY, file, socket, non-Unix platform) it falls back to the existing blocking stdio() handles.
It returns (StdioReader, StdioWriter), public enums implementing AsyncRead/AsyncWrite that convert into a transport through the existing IntoTransport tuple impl, so call sites stay portable:
```
let service = server.serve(stdio_pipes()).await?;
```

stdio() is intentionally left unchanged: changing its return type is a breaking public API change (see VERSIONING.md and the public-api CI job). If maintainers prefer stdio() itself to use the fast path, that needs a major release — happy to follow up either way.

Design notes

Both descriptors are fstat-checked (S_IFIFO) before either is handed to Tokio. from_owned_fd switches the descriptor to O_NONBLOCK, which is shared across descriptors of the same open file description, so a partial conversion would leave the blocking fallback with non-blocking stdio.
The transport owns duplicated descriptors; dropping it does not close the process's real stdin/stdout.
On Unix, stdio_pipes() must be called inside a Tokio runtime with IO enabled (Tokio's from_owned_fd panics otherwise); this is documented on the function.
transport-io now enables tokio/net for the pipe types. Precedent: transport-streamable-http-client-unix-socket already enables tokio/net.

Tests

pipe_transport_round_trips_over_fifos (unix): spawns cat, wraps real Stdio::piped() FIFO descriptors through the same code path, round-trips a JSON-RPC line, and checks the peer exits cleanly.
pipe_transport_falls_back_for_non_fifos (unix): character devices are rejected.
stdio_pipes_builds_an_async_rw_transport: the returned pair satisfies the AsyncRwTransport/IntoTransport bounds used by serve.
stdio_pipes_falls_back_to_blocking_handles_on_windows.

Verification

cargo test -p rmcp --lib → 216 passed.
cargo test -p rmcp --lib --features transport-io → 218 passed (Windows).
Unix tests were compile-checked with cargo check --target x86_64-unknown-linux-gnu --lib --tests --features transport-io; they execute on CI (ubuntu).
cargo clippy -p rmcp --all-targets --all-features -- -D warnings → clean.
cargo clippy -p rmcp --all-targets --no-default-features --features <all except local> -- -D warnings → clean.
cargo +nightly fmt → clean for the changed files.

No throughput numbers are claimed here; #1301's harness (Apple M3 Pro) is the reference, and this change was developed on Windows.

Closes #1301

Contribution prepared with an AI coding agent (opencode); tests were written first and fail without the fix.

DaleSeo · 2026-09-28T00:50:10Z

+fn try_pipe_transport() -> Option<(StdioReader, StdioWriter)> {
+    use std::os::fd::AsFd;
+
+    let read = std::io::stdin().as_fd().try_clone_to_owned().ok()?;
+    let write = std::io::stdout().as_fd().try_clone_to_owned().ok()?;
+    pipe_transport(read, write)
+}


try_clone_to_owned() duplicates the file descriptor, so the new fd shares its open file description with fd 0 or 1. When from_owned_fd sets O_NONBLOCK, the process's stdin or stdout stays non-blocking for the rest of its life, even after the transport is dropped.

itsmunzir · 2026-09-28T05:42:32Z

Good catch - you're right that O_NONBLOCK lives on the open file description, so it is shared with fd 0/1 and outlives a dropped transport. That is inherent to driving an anonymous pipe from the IO reactor: from_owned_fd sets the flag via fcntl(F_SETFL), and there is no way to have the reactor read a pipe without putting the whole description into non-blocking mode. The reporter's sketch in #1301 has the same property.

What the code does guard against is the partial case: both descriptors are verified as FIFOs before either is converted, so the fallback path can never receive a description that has already been flipped, and the two halves are always converted together.

Options if you want the process-wide effect contained:

A Drop that restores the original file-status flags once both halves have been dropped. Care needed: with a split transport, one half can drop while the other is still being driven, and clearing the flag then would break the reactor - the restore has to be tied to the last owner, not each half.
Keep the behavior and state it on stdio_pipes() as an explicit caveat for in-process embedders - a dedicated stdio MCP server owns its stdio for its lifetime, which is the intended call site, and stdio() remains untouched for everyone else.

I can implement either; my lean is 2 plus a doc note, since 1 can only restore the flag after the fact and has the split-transport edge above. But you know the SDK's expectations better - happy to go your way.

DaleSeo · 2026-09-28T19:27:31Z

@itsmunzir Thanks for the careful analysis. The split-transport point about option 1 is a good one.

On Linux, we can avoid the leak entirely. Opening /proc/self/fd/0 and /1 with O_NONBLOCK set means a read-only FIFO open won't block. It also creates a new open file description, so fds 0 and 1 stay untouched. macOS has no equivalent, so I'd use the blocking fallback there.

I'd rather not rely on a caveat in the docs, since Command::spawn lets children inherit stdin by default. The partial case can still happen, too. Tokio sets O_NONBLOCK before registering the fd, so if Sender fails, stdin has already been flipped.

Could you add an Ubuntu test to check that fd 0's flags are unchanged after stdio_pipes()?

itsmunzir · 2026-09-29T06:35:05Z

Done in 8f1193b. The Linux path now reopens /proc/self/fd/0 and /1 with O_NONBLOCK, so the new descriptors have their own open file descriptions and the process's stdin and stdout keep their flags. macOS and Windows keep the blocking fallback, and the pipe variant is Linux-only now.

Tests added:

reopening_a_fifo_keeps_the_original_flags — the reopened descriptor is non-blocking, the source descriptor stays blocking, and the reopened descriptor is a FIFO.
stdio_pipes_leaves_descriptor_zero_flags_alone — the check you asked for.
fifo_detection_rejects_character_devices — replaces the old non-FIFO wrapper test.
The round-trip test now uses the Linux wrapper directly.

Verified here: Windows tests 218/218, the Linux target compiles, and clippy passes with the CI feature sets. The Linux tests run on CI.

itsmunzir · 2026-10-04T10:19:45Z

Gentle ping on this one. The /proc/self/fd rework is pushed in 8f1193b and CI is green — the Linux path reopens fd 0/1 so the original descriptors keep their flags, with the blocking fallback on macOS and Windows. Happy to adjust anything before review.

itsmunzir · 2026-10-05T05:45:26Z

The commitlint failure is fixed: the rework commit body had 221/274/167-character lines, over the 100-character body-max-line-length. It is rewrapped and signed off (bc5160b).

On Check MSRV: this is dependency drift, not this PR. The job reads rust-version = "1.88" from rmcp and builds with 1.88, but Cargo.lock is gitignored, so a fresh resolution now picks uuid@1.27.0, which requires rustc 1.89 — any branch that resolves today hits it (error: rustc 1.88.0 is not supported by the following package: uuid@1.27.0 requires rustc 1.89.0). If you want, I can pin it in the CI job (cargo update -p uuid --precise 1.26.1 before the MSRV build) — say which version you prefer and I will add it here.

DaleSeo · 2026-10-05T18:45:41Z

The MSRV failure isn't from your change. It was fixed on main in #1316. Could you rebase onto the latest main and push? A re-run alone won't pick up the fix.

`transport::stdio()` reads and writes through Tokio's blocking thread pool, so every message on a piped stdio connection pays a cross-thread hand-off. MCP clients launch stdio servers with FIFOs for stdin/stdout, which Tokio's Unix pipe driver can drive from the IO reactor instead. `stdio_pipes()` wraps the standard streams as non-blocking pipes when both are FIFOs and otherwise falls back to the blocking `stdio()` handles, so the returned `(StdioReader, StdioWriter)` pair still converts into a transport on every platform. TTYs, files, sockets, and Windows keep today's behavior. `stdio()` is left unchanged because changing its return type would be a breaking public API change; this constructor is additive. The `transport-io` feature now enables `tokio/net` for the pipe types. Refs modelcontextprotocol#1301

try_clone_to_owned duplicates the descriptor, so the duplicate shares its open file description with fd 0 or 1. Tokio's O_NONBLOCK then leaked into the process's own standard streams, and into children that inherit them. stdio_pipes() now opens /proc/self/fd/0 and /1 with O_NONBLOCK on Linux. The kernel gives the new descriptors their own file descriptions, so the flags stay private to the transport. macOS has no /proc, so it keeps the blocking fallback; the pipe variant is Linux-only now. Tests: reopening a FIFO keeps the source descriptor blocking, descriptor 0 keeps its flags across stdio_pipes(), and the round-trip and non-FIFO cases moved to Linux. Signed-off-by: itsmunzir <itsmunzir@users.noreply.github.com>

itsmunzir · 2026-10-06T06:04:44Z

Rebased onto 79437f2 and pushed (65f149a, 2e2d6b); cargo check -p rmcp --all-features is clean. Thanks for the pointer to #1316.

DaleSeo · 2026-10-11T16:32:10Z

+    let stdin = std::io::stdin().as_fd().try_clone_to_owned().ok()?;
+    if !is_fifo(&stdin) {
+        return None;
+    }
+    let stdout = std::io::stdout().as_fd().try_clone_to_owned().ok()?;
+    if !is_fifo(&stdout) {
+        return None;
+    }
+
+    let read = reopen_nonblocking("/proc/self/fd/0", false)?;
+    let write = reopen_nonblocking("/proc/self/fd/1", true)?;


try_pipe_transport only duplicates file descriptors 0 and 1 to call fstat on them. Then is_fifo duplicates them again, and the code later opens /proc/self/fd/N. So the descriptor it checks isn’t the one it uses. Is there a reason not to reopen the descriptors first and run is_fifo on the ones we actually pass to Tokio?

DaleSeo · 2026-10-11T16:32:10Z

+/// Reader half of the transport returned by [`stdio_pipes`].
+#[non_exhaustive]
+pub enum StdioReader {
+    /// Blocking standard input, as returned by [`stdio`].
+    Blocking(tokio::io::Stdin),
+    /// Non-blocking standard input backed by a Linux pipe.
+    #[cfg(target_os = "linux")]
+    Pipe(tokio::net::unix::pipe::Receiver),
+}


StdioReader and StdioWriter are public, along with their variants. That makes tokio::net::unix::pipe::Receiver part of rmcp's API, and the available variants vary by target OS. Do callers need to know which path was taken?

DaleSeo · 2026-10-11T16:32:10Z

+    /// The check the reviewer asked for: descriptor 0 keeps its flags.
+    #[cfg(target_os = "linux")]
+    #[tokio::test]
+    async fn stdio_pipes_leaves_descriptor_zero_flags_alone() {
+        use std::os::fd::AsRawFd;
+
+        use super::stdio_pipes;
+
+        let before = open_flags(std::io::stdin().as_raw_fd());
+        let _transport = stdio_pipes();
+        let after = open_flags(std::io::stdin().as_raw_fd());
+        assert_eq!(before, after);
+    }


stdio_pipes() only reopens anything when both file descriptors 0 and 1 are FIFOs. Under cargo test on CI, stdin usually isn't a pipe, so the test can pass without exercising the code it's meant to cover. How can we make sure it actually goes through the reopen path on the Ubuntu runner?

DaleSeo · 2026-10-11T16:32:10Z

+pub fn stdio_pipes() -> (StdioReader, StdioWriter) {
+    #[cfg(target_os = "linux")]
+    if let Some(pair) = try_pipe_transport() {
+        return pair;
+    }
+    (
+        StdioReader::Blocking(tokio::io::stdin()),
+        StdioWriter::Blocking(tokio::io::stdout()),
+    )
+}


Every failure in the detection chain is swallowed by .ok()?. If someone reports that stdio_pipes() isn't faster, nothing tells us whether the pipe path was taken. Would a tracing event on fallback be worth it, since the crate already depends on tracing?

DaleSeo · 2026-10-11T16:32:10Z

+}
+
+/// Reader half of the transport returned by [`stdio_pipes`].
+#[non_exhaustive]


Public types should implement Debug, and all the wrapped Tokio types already do. The same goes for StdioWriter` below.

Suggested change

#[non_exhaustive]

#[derive(Debug)]

#[non_exhaustive]

DaleSeo · 2026-10-11T16:32:10Z

+        let _ = std::fs::remove_file(&path);
+    }
+
+    /// The check the reviewer asked for: descriptor 0 keeps its flags.


Once this is merged, "the reviewer" won't mean anything, so the comment should name the property being tested.

Suggested change

/// The check the reviewer asked for: descriptor 0 keeps its flags.

/// `stdio_pipes()` must not set `O_NONBLOCK` on the process's own stdin.

DaleSeo · 2026-10-11T16:32:11Z

+    #[tokio::test]
+    async fn fifo_detection_rejects_character_devices() {


This test never uses .await, so a plain #[test] is enough. It also makes it clear that the test doesn't touch the reactor. The same goes for reopening_a_fifo_keeps_the_original_flags above.

Suggested change

#[tokio::test]

async fn fifo_detection_rejects_character_devices() {

#[test]

fn fifo_detection_rejects_character_devices() {

DaleSeo · 2026-10-11T16:32:11Z

+    #[cfg(windows)]
+    #[tokio::test]
+    async fn stdio_pipes_falls_back_to_blocking_handles_on_windows() {


macOS now uses the same fallback in all cases, so this test can run on every non-Linux target.

Suggested change

#[cfg(windows)]

#[tokio::test]

async fn stdio_pipes_falls_back_to_blocking_handles_on_windows() {

#[cfg(not(target_os = "linux"))]

#[tokio::test]

async fn stdio_pipes_falls_back_to_blocking_handles_off_linux() {

itsmunzir requested a review from a team as a code owner September 27, 2026 12:17

github-actions Bot added T-dependencies Dependencies related changes T-config Configuration file changes T-core Core library changes T-transport Transport layer changes labels Sep 27, 2026

DaleSeo reviewed Sep 28, 2026

View reviewed changes

itsmunzir force-pushed the feat/stdio-pipes branch from 8f1193b to bc5160b Compare October 5, 2026 05:45

itsmunzir added 2 commits October 6, 2026 08:54

itsmunzir force-pushed the feat/stdio-pipes branch from bc5160b to f2e2d6b Compare October 6, 2026 06:04

DaleSeo reviewed Oct 11, 2026

View reviewed changes

	/// The check the reviewer asked for: descriptor 0 keeps its flags.
	/// `stdio_pipes()` must not set `O_NONBLOCK` on the process's own stdin.

		#[tokio::test]
		async fn fifo_detection_rejects_character_devices() {

Conversation

itsmunzir commented Sep 27, 2026

Summary

Design notes

Tests

Verification

Uh oh!

DaleSeo Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

itsmunzir commented Sep 28, 2026

Uh oh!

DaleSeo commented Sep 28, 2026

Uh oh!

itsmunzir commented Sep 29, 2026

Uh oh!

itsmunzir commented Oct 4, 2026

Uh oh!

itsmunzir commented Oct 5, 2026

Uh oh!

DaleSeo commented Oct 5, 2026

Uh oh!

itsmunzir commented Oct 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

DaleSeo Sep 28, 2026 •

edited

Loading